---
title: "Combo Box"
description: An advanced dropdown component that allows users to search, filter, and select options dynamically for a smoother selection experience.
order: 1
published: true
references: ["https://react-spectrum.adobe.com/react-aria/ComboBoxhtml#props"]
---

## Basic

A combo box combines a text input with a listbox, allowing users to filter options to match what they're looking for.
<How minW60 toUse="pickers/combo-box/combo-box-demo" />

## Installation
```bash
npx shadcn@latest add @intentui/combo-box
```

## Composed components
<Composed components={['field', 'dropdown', 'popover', 'button']}/>

## Manual installation
```bash
npm i react-aria-components @heroicons/react
```

<SourceCode toShow='combo-box'/>

## Anatomy
```
import { Label } from "@/components/ui/field"
import {
  ComboBox,
  ComboBoxInput,
  ComboBoxContent,
  ComboBoxItem,
} from "@/components/ui/combo-box"
```

```
<ComboBox name="users">
  <Label>Users</Label>
  <ComboBoxInput placeholder="Select a user" />
  <ComboBoxContent>
    <ComboBoxItem>John Lennon</ComboBoxItem>
    <ComboBoxItem>Paul McCartney</ComboBoxItem>
    <ComboBoxItem>George Harrison</ComboBoxItem>
    <ComboBoxItem>Ringo Starr</ComboBoxItem>
  </ComboBoxContent>
</ComboBox>
```

## Using avatars
The combo box can be configured to display avatars instead of just regular text.
<How minW60 toUse="pickers/combo-box/combo-box-avatar-demo" />

## Section
A combo box can display items grouped together in sections.
<How minW60 toUse="pickers/combo-box/combo-box-section-demo" />

## Readonly
When the combo box is in a readonly state, it cannot be edited.
<How minW60 toUse="pickers/combo-box/combo-box-readonly-demo" />

## Label
If the `children` of a `ComboBoxItem` is a string, the `ComboBoxLabel` will automatically wrap it. However, if you're including additional elements like an icon or avatar, you'll need to manually wrap the label, as shown below:

```
<ComboBoxItem id={item.id} textValue={item.name}>
  <Avatar src={item.image_url} />
  <ComboBoxLabel>{item.name}</ComboBoxLabel>
</ComboBoxItem>
```

## Details description
If you need to provide more information about an option, use the `ComboBoxDescription` component to display additional details.
<How minW60 toUse="pickers/combo-box/combo-box-detail-description-demo" />

## Validation
If a user submits the form without selecting an item, an error message will appear.
<How minW60 toUse="pickers/combo-box/combo-box-validation-demo" />

## Controlled
There are two ways to control the combo box: using the `onInputChange` prop or the `onSelectionChange` prop. These methods serve different purposes, as illustrated in the examples below. Both examples follow the same approach, defining `id` and `textValue` for the options.

When you only need the `textValue` of the selected option, use the `onInputChange` prop. However, if you need to obtain the actual `id` of the selected option, the `onSelectionChange` prop is the appropriate choice.

### Input
This combo box is controlled by the `onInputChange` prop.
<How minW60 toUse="pickers/combo-box/combo-box-controlled-demo" />

### Selection
This combo box is controlled by the `onSelectionChange` prop.
<How minW60 toUse="pickers/combo-box/combo-box-controlled-selection-demo" />

## Disabled
When the combo box is disabled, it becomes non-interactive and cannot be edited.
<How minW60 toUse="pickers/combo-box/combo-box-disabled-demo" />
